home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / qbbs / qcktop26.zip / QCKTOP40.DOC < prev    next >
Text File  |  1991-04-16  |  45KB  |  1,164 lines
  1.                        Top40 - version 2.6
  2.  
  3.     WILDCAT! BBS, QuickBBS, and PowrBBS Top 40 user utility
  4.  
  5.                          January 7, 1990
  6.  
  7.                      Revised April 16, 1991
  8.  
  9.     (C) Copyright 1990 Judson McCranie.  All rights reserved.
  10.  
  11.                        Judson S. McCranie
  12.                        Mantissa Software
  13.                        1505 E. Park, #G4
  14.                        Valdosta, GA 31602
  15.                        Ph: (912) 242-1405
  16.  
  17. NOTE: This documentation applies to three versions of Top40:
  18. WCTop40 for Wildcat BBS, QckTop40 for QuickBBS, and PwrTop40 for
  19. PowrBBS.  The actual program files are prefixed with "WC", "Qck",
  20. or "Pwr" except for the output bulletin files.
  21.  
  22. The latest version of the program and support are available
  23. through:
  24.  
  25.                        Bad Lands (QuickBBS)
  26.                   300/1200/2400/9600 HST 8,N,1.
  27.                         Sysop: Andy Smith
  28.                          (912) 247-6977
  29.  
  30. This program is distributed on a "Shareware" (try-before-you-buy)
  31. basis.  You are free to copy it and to distribute copies at cost. 
  32. You may not alter the program (or its documentation) or sell it
  33. for profit.  
  34.  
  35. You may try this program for a period of 30 days.  If you
  36. continue to use this program after the 30 day period then you
  37. must register it by sending your the name of your board, the
  38. board's phone number, and your name & address along with the
  39. program name and version number with a $20 registration and
  40. license fee to me at the address above.  You will receive support
  41. for the program, announcements of new versions of this program,
  42. and information about several other programs.  Please send any
  43. inquires, comments, or suggestions to me at the address above.      
  44.  
  45.  
  46. WHAT IS TOP40:
  47.  
  48. Top40 is a Sysop utility designed to create over a dozen
  49. different top user bulletins.  It makes full use of the activity
  50. log and creates a user data file which is updated with each use. 
  51. The WC version of the program is designed to work with WILDCAT
  52. 2.xx but may work with previous versions.  The Qck version is
  53. designed to work with QuickBBS version 2.6x, but may work with
  54. other versions.  The Pwr version of the program is designed to
  55. work with PowrBBS version 1.30 but should work with other
  56. versions.
  57.  
  58. You should find the following files in the archived file.
  59.  
  60.   xxxTop40.DOC  this documentation file
  61.   Top40   .XM?  examples of bulletins
  62.   xxTop40I.EXE  sysop installation program (PwrT40I.EXE for Pwr)
  63.   xxxTop40.EXE  program to generate bulletins
  64.   WCTop40C.EXE  converts files from 1.5x format to 2.0x (WC only)
  65.   WCT40C23.EXE  converts files from 2.1x/2.2 to 2.3/2.4 (WC only)
  66.   ORDERBLK.DOC  registration form
  67.   OTHER   .DOC  other programs by this author
  68.  
  69. where xxx = "WC", "QCK", or "PWR" and xx = "WC", "QCK", or "PW".
  70.  
  71. The program will generate the following files in the current
  72. directory:
  73.  
  74.   xxTop40.OPT  generated by the installation program
  75.   xxTop40.DAT  generated by the main program
  76.   xxTop40.SIZ  generated by then main or conversion program
  77.  
  78. where xx = "WC", "Qck", or "Pwr".
  79.  
  80. These files should be in the same directory as the Top40 EXE
  81. files and that directory should be the current directory when
  82. Top40 is run (i.e. - don't run Top40 with a path).  You can
  83. specify a path to the activity log and user data files and a path
  84. to which the bulletin files will be written.
  85.  
  86. This program is a utility to add top user lists to the WILDCAT
  87. BBS, QuickBBS, or PowerBBS.  It can be run after each call or as
  88. an event.  You can specify the number of users that will appear
  89. on the list, or disable any report.  The program compiles reports
  90. of the top users of each of following from the activity log: 
  91.  
  92.      callers
  93.      posters (messages)
  94.      uploaders
  95.      downloaders
  96.      door openers
  97.      carrier droppers (Use as a bulletin if D/Cs are really bad)
  98.      security violators (recommended for yourself only)
  99.  
  100. Note: The program currently considers any termination of the call
  101. other than a normal logoff a "carrier drop".  It could more
  102. properly be called an abnormal termination or logoff.
  103.  
  104. It also will generate these compilation reports:
  105.  
  106.      newest users
  107.      best users (based of total points > 0)
  108.      BBS losers (based on total points < 1)
  109.      All users  (based on total points)
  110.      
  111.      triple list - report of any three of the above categories
  112.  
  113. Three "triple lists" are available.
  114.  
  115. The most unique feature is the list of the top users, which is
  116. based on a weighted point system.  For instance, you can assign 2
  117. points for each call, 1 point for each message, 10 points for
  118. each upload, -5 points for each download, -10 points for each
  119. security violation, etc.  The user's total points is based on
  120. this value calculated from his statistics.
  121.  
  122.     Item Used             Recommended Point Value
  123.  
  124.     Number of Calls                  1 to   2
  125.     Number of Messages posted        2 to   4
  126.     Number of Uploads               10 to  25
  127.     Number of Downloads             -5 to -15
  128.     Number of Door uses              1 to   3
  129.     Number of Carrier drops         -1 to  -3
  130.     Number of Security violations   -3 to  -5
  131.  
  132. Feel free to experiment with the point values until the resulting
  133. scores suit you.  You should probably consider a balance between
  134. the points for uploads and the points for downloads.  For
  135. instance, if you expect a 5:1 upload:download ratio, the point
  136. value for an upload should probably be 5 times as large (in
  137. absolute value) as the value for a download (e.g. +20 for an
  138. upload, -4 for a download).
  139.  
  140. The "newest users" is a list of the newest users.  The newest
  141. user will be #1 on the list, etc.  This should be encouraging to
  142. new users since they will get to see their names at the top of
  143. the list the next time they call.  Otherwise, it would be quite a
  144. while before they make any of the top user lists.
  145.  
  146.  
  147. CHANGES IN VERSION 2.6:
  148.  
  149. Added support for QuickBBS.
  150.  
  151.  
  152. CHANGES IN VERSION 2.5:
  153.  
  154. Fixed a bug in the Wildcat version installation program.  
  155.  
  156. Added the option of entering the name of the user data file.
  157.  
  158.  
  159. CHANGES IN VERSION 2.4:
  160.  
  161. Faster reading and writing of disk files.
  162.  
  163. Smaller EXE file.
  164.  
  165.  
  166. CHANGES IN VERSION 2.3:
  167.  
  168. Add support for PowrBBS.
  169.  
  170. Add an extension option for ASCII files.
  171.  
  172. New options file format.
  173.  
  174.  
  175. CHANGES IN VERSION 2.2:
  176.  
  177. The "Purge deleted users" choice in the installation program will
  178. delete any users from the Top40 data file that have been deleted
  179. from the Wildcat user data base.  The "Delete users" (which
  180. deleted individual users) has been removed from the installation
  181. program.  I no longer see a need for it, but if you think it
  182. should stay in the program please let me know.
  183.  
  184. The background color problem in the ANSI screens has been fixed. 
  185. (Thanks to Bob Lias for informing me of the problem.)
  186.  
  187. You can now specify the path to the user data file (USERFILE.DAT
  188. or USERS).
  189.  
  190.  
  191. CHANGES IN VERSION 2.14:
  192.  
  193. There was a bug in versions 2.1 through 2.13 in the "newest user
  194. list".  (Thanks to Cam DeBuck for pointing this out.)  See "How
  195. bugs creep into programs" for more details.
  196.  
  197.  
  198. CHANGES IN VERSION 2.1:
  199.  
  200.   Support for Wildcat version 2.15.
  201.  
  202.   Fix a bug when a user is deleted by WCRepair.
  203.  
  204.   Option of ANSI screens.
  205.  
  206.   Option of counting down to number 1 on the lists.
  207.  
  208.  
  209. SUMMARY OF CONVERSION FOR USERS OF VERSIONS PRIOR TO 2.3:
  210.  
  211. The options data file (WCTop40.OPT) has been reorganized.  You
  212. can't simply run the program with the old option file like you
  213. could when going from version 2.0x to 2.1x or 2.2, or from 2.1x
  214. to 2.2.  
  215.  
  216. Here is my recommendation for users of previous versions who
  217. which to upgrade to the current version while retaining their
  218. data.  There are several things you could do to upgrade the data
  219. files.  In all cases, I recommend making a backup copy of the
  220. data files before doing the conversion.  More details follow, but
  221. my recommendations are:
  222.  
  223. For users of 2.1x or 2.2, the easiest way to get to 2.4 (or 2.3x)
  224. is to run WCT40C23 to convert the options file to the new format,
  225. and then run the installation program and check all options.  In
  226. particular, you need to check the ASCII file extension option if
  227. you want something other than the default "ASC".  Alternatively,
  228. you could delete the "WCTop40.OPT" file and reinstall the
  229. parameters.
  230.  
  231. For users of version 2.0x the easiest thing to do is run the
  232. program WCT40C23 and then run the installation program and check
  233. the options.  In particular, you need to check the ASCII file
  234. extension option if you want something other than the default
  235. "ASC" and the options for the ANSI screens.  Alternatively,
  236. delete the file WCTop40.OPT and reinstall the options.
  237.  
  238. For users of version 1.3x, 1.4x, and 1.5x, you need to run the
  239. program WCTop40C.  This will bring the file WCTop40.DAT up to the
  240. current standard and the option file (WCTop40.OPT) up to version
  241. 2.0 standard.  Then see the "For users of version 2.0x" above. 
  242. Alternatively, you could skip the upgrade programs, delete the
  243. options file (WCTop40.OPT), reinstall the options, and then edit
  244. the user database to check the include/exclude option on each
  245. user.
  246.  
  247.  
  248. USERS OF VERSION 2.1x OR 2.2:
  249.  
  250. You can use the program WCT40C23.EXE to convert the option file
  251. to the new (version 2.3/2.4) format.  In version 2.3 and 2.4 the
  252. extension for the ASCII files has been separated from the file
  253. names.  The default is "ASC".  You can change this by running the
  254. installation program after the conversion program. 
  255. Alternatively, you can delete the options file (WCTop40.OPT or
  256. PwrTop40.OPT) and run the installation program again.
  257.  
  258.  
  259. USERS OF ANY VERSION PRIOR TO 2.1:
  260.  
  261. I recommend deleting the file Top40.OPT and reinstalling the
  262. parameters as being the easiest way to get up and running with
  263. this version.  Users of 1.x see the following note.
  264.  
  265. Before version 2.1 there was a problem when you delete a user and
  266. use WCRepair.  WCRepair changes user's record number (that
  267. appears in ACTIVITY.LOG).  Versions before 2.1 used this record
  268. number to match up records (as opposed to the names).  If you
  269. were using Top40 then deleted a user, then ran Top40 again then
  270. Top40's data file (Top40.DAT) will be corrupted - users will be
  271. listed more than once with their old and new record numbers. 
  272. These seems to be no feasible way to correct the dat file since
  273. the data for an old user that had a user's new record number will
  274. be lost.  The best thing to do is to delete Top40.DAT and
  275. Top40.SIZ and let Top40 rebuild the data file.
  276.  
  277. Versions of Top40 prior to 2.1 will not work correctly with
  278. Wildcat! version 2.15 (or later versions).  The reason is that
  279. the versions before 2.1 read the record number from the activity
  280. log and used that to match records.  In Wildcat version 2.1, the
  281. second line of the calling record had "Record number:", whereas
  282. version 2.15 has "Record:".  Old versions of Top40 looked for the
  283. former wording.  Version 2.1 of Top40 avoids the problem (and
  284. other problems) by going by the user name only.
  285.  
  286.  
  287. USERS OF VERSION 2.0x:
  288.  
  289. If you want to generate ANSI screens then you need to run the
  290. installation program and set the colors and the extension of the
  291. ANSI files.  There is also a new option of counting down to
  292. number 1 on the lists.  
  293.  
  294.  
  295. USERS OF VERSION 1.3, 1.4x, OR 1.5x: 
  296.  
  297. The format of the file Top40.OPT has been changed slightly to
  298. accommodate new features.  You can either:
  299.  
  300.   1) Delete the file Top40.OPT and run the installation program
  301.      to reinstall the options
  302.  
  303.   2) Edit the file Top40.OPT manually.
  304.  
  305. It is a good idea to make backup copies of Top40.DAT and
  306. Top40.OPT before running the conversion program (Top40C).  All
  307. Top40C does is set the include/exclude option on each user.  If
  308. you don't use the conversion program you will need to use the
  309. installation program to edit the user data and set everyone's
  310. inclusion/exclusion option.
  311.  
  312. If you are converting from version 1.3, 1.4x, or 1.5x, the
  313. options file should be converted either by hand or the conversion
  314. program before the data file is converted.  The conversion
  315. program expects the options file to be in 1.5 format.  That is,
  316. if you convert the options file by hand to 1.5 format then you
  317. should run the conversion program to convert the options file and
  318. data file.  Do not convert the options file to 2.0 format by
  319. hand, otherwise the "excluded user" information will be lost.
  320.  
  321. After converting to 2.0 format then you can run WCT40C23 to
  322. convert to version 2.3/2.4 format.  (See "USERS OF VERSION 2.1x
  323. OR 2.2".)
  324.  
  325. If this seems confusing, here is a recap:
  326.  
  327. Users of version 1.3 or 1.4x, do either:
  328.  
  329.   1) Convert the options file to 1.5 format by hand and 
  330.      then see option 1 below.
  331.  
  332.   2) Delete options file and reinstall - see option 2 below.
  333.  
  334.   3) Convert options to 2.0 format by hand - see option 3 below.
  335.      Then convert to 2.4.
  336.  
  337.  
  338. Users of version 1.5x, do either:
  339.  
  340.   1) Run the conversion and tell it to convert BOTH the options
  341.      file AND the data file.
  342.  
  343.   2) Delete Top40.OPT and reinstall options, then run the
  344.      conversion program and tell it NOT to convert the options
  345.      file but DO tell it convert the data file.
  346.  
  347.   3) Convert the options file to 2.0 format by hand and then run
  348.      the conversion program - telling it NOT to convert the
  349.      options file but DO convert the data file.  Then use the
  350.      installation program to exclude the users you want to
  351.      exclude (if any).  Then run the conversion program WCT40C23
  352.      to convert to version 2.3/2.4 format.
  353.  
  354.  
  355. INSTALLATION:
  356.  
  357. The opening screen of the installation program (Top40I) gives you
  358. the following options:
  359.  
  360.     General options (board name and file paths)
  361.     Category options (calls, messages, etc)
  362.     Point lists (lists based on weighted points)
  363.     Triple lists (combination of any three lists)
  364.     Add users
  365.     Edit users
  366.     Purge deleted users from file (replaces "Delete users")
  367.     List users to printer
  368.     Quit installation
  369.  
  370. in the form of a standard pick list.  You can use the cursor to
  371. get down to the desired item and press <ENTER> or you can simply
  372. press the first letter of the option.
  373.  
  374. To use, enter Top40I at the DOS prompt and answer the questions
  375. you will be asked.  The edit screens use standard editing keys -
  376. arrows, backspace, home, end, <ENTER>, etc.  When you have
  377. finished with your entries to a given screen press <CTRL-ENTER>
  378. to save the configuration.  Press <ESC> to exit from the screen
  379. without saving changes.
  380.  
  381. Once you have the installation complete, you need only type in
  382. Top40 and hit return to compile the data file, or you can wait
  383. for it to be called the completion of the next call or event.
  384.  
  385. The program Top40I is the sysop's installation program where you
  386. can set various options.  There are four option screens.
  387.  
  388. The first option screen allows you enter the name of the board
  389. and enter paths for the activity log file and for the generated
  390. reports.  There is not much error checking on the file names and
  391. paths you enter, so be sure to enter valid paths and file names. 
  392. The program will append a "\" to the end of the path, if needed. 
  393. Otherwise, the full path must be specified.  It is not necessary
  394. to put the drive code in the path if it is the same as the
  395. current drive.
  396.  
  397. The second option screen is for entering options pertaining to
  398. each of the categories.  For each category you can set the output
  399. filename, whether or not to go down the columns (Y/N), the number
  400. of columns to print (2 or 3), and the number of each you want
  401. listed (a zero keeps the report from being generated).  For each
  402. of the categories you can enter the number of points that item
  403. should count for the user's total point standing.  A value of
  404. zero points means that the item is not included in the total
  405. point calculation.  Even if you do not select a report for an
  406. individual category it still counts in the total user points.
  407.  
  408. The third option screen allows you enter options pertaining to
  409. the compilation reports ("newest users", "best users", "BBS
  410. losers", and "all users").  You can enter the number you want
  411. printed (zero means no report will be generated), the file name
  412. to which the report will be written, whether or not to go down
  413. columns (Y/N), and the number of columns (2 or 3).  The all users
  414. will list all users in order of total points, with an upper limit
  415. of the number you specify.  To list all users, set this value to
  416. a high number (default is 1500).
  417.  
  418. The fourth option screen allows you enter options pertaining to
  419. the the triple lists.  You can enter the number you want printed
  420. (zero means no report will be generated) and the file name to
  421. which the report will be written.  This screen also sets you
  422. select the three categories to be used in each of three triple
  423. lists.  For each triple list you can select any three of the
  424. categories listed above ("calls" through "security violators",
  425. "newest users", "best users", and "BBS losers").  You can put the
  426. three in any order.  The option screen will show a line with
  427. three boxes with the name of one of the categories in each box
  428. for each triple list.  With the cursor on a box, press the "+"
  429. key or the "-" key to change the selection.
  430.  
  431. Note:  The program builds its data file from your current
  432. activity log (see "EXECUTION" for more details).  It reads all of
  433. the call records in activity log to initialize its data file.  If
  434. you have old copies of your activity log still available, you can
  435. include that information in the data file too by taking the
  436. following steps:
  437.  
  438.   1) Make a copy of your current activity log.
  439.  
  440.   2) Make a copy of Top40.SIZ if it exists.
  441.  
  442.   3) Repeat for each old activity log you have:
  443.  
  444.       A. Delete Top40.SIZ if it exists.
  445.    
  446.       B. Copy your old activity log to "ACTIVITY.LOG" (in the 
  447.          proper directory).
  448.  
  449.       C. Run Top40.  (It will add the data in the log.)
  450.  
  451.   4) Restore your original activity log.
  452.   
  453.   5) Restore the original Top40.SIZ if it existed, 
  454.      otherwise delete Top40.SIZ.
  455.  
  456. This is an example of the file Top40.OPT that is generated by the
  457. installation program and read by the programs.  This is the new
  458. format for version 2.3.
  459.  
  460. 2.3                          | Version number 
  461. Board Name                   | BBS name
  462. \DATA\                       | Path to activity log
  463. \WC\                         | Path to output files
  464. \WC\                         | Path to BBS user data file
  465. ASC                          | Extension for ASCII output files
  466. SCR                          | Extension for ANSI output files
  467. N                            | Count down to #1 (Y/N)
  468.   1 11 12 15 10 14 13        | ANSI color codes
  469. Top40CAL N 2   30      1     |{These lines are parameters for the
  470. Top40MES N 2   30      3     |{single-item bulletins.  See the 
  471. Top40UPL N 2   30     20     |{description below for detailed
  472. Top40DNL N 2   30     -5     |{information.
  473. Top40DOR N 2   30      2     |     
  474. Top40DRP N 2   30     -2     |
  475. Top40SEC N 2   30     -4     |
  476. Top40NEW N 2   30      0     |
  477. Top40TOP N 2   30      0     |
  478. Top40BOT N 2   30      0     |
  479. Top40ALL N 2 1000      0     |
  480. Top40TR1 15  7  2  3         |{These lines are parameters for the
  481. Top40TR2 15  1  4  8         |{triple lists.  See descriptions
  482. Top40TR3 15  5  6  9         |{below for detailed information.
  483. ACTLOG1                      | Name of PowrBBS activity log 
  484. USERINFO.DAT                 | Name of the user data file
  485.  
  486. The lines of the file are:
  487.  
  488. Version number of installation program 
  489.  
  490. Board Name
  491.  
  492. Path for the activity log (if not in current directory)
  493.  
  494. Path for ASCII output (if not in current directory)
  495.  
  496. Path for user data file (if not in current directory)
  497.  
  498. A line giving the extension of the ASCII output screens.
  499.  
  500. A line giving the extension of the ANSI output screens, if they
  501. are to be generated.  If this is blank the ANSI versions of the
  502. bulletins will not be generated.  For PowrBBS this should be "C"
  503. if ANSI bulletins are desired.  Also in PowrBBS, the extensions
  504. are not appended.
  505.  
  506. A line giving "Y" or "N" - Y indicates count lists down to #1.
  507.  
  508. A line containing 7 numbers between 0 and 15 that give the
  509. numbers of the colors of the background, frame, heading, integer,
  510. legend, name, and value, respectively.  The color numbers are:
  511.  
  512.          #  Color          #  Color      
  513.  
  514.          0  Black          8  Dark gray
  515.          1  Blue           9  Light blue
  516.          2  Green         10  Light green
  517.          3  Cyan          11  Light cyan
  518.          4  Red           12  Light red
  519.          5  Magenta       13  Light magenta
  520.          6  Brown         14  Yellow
  521.          7  Light gray    15  White
  522.  
  523. Note that these colors are the standard DOS color numbers - NOT
  524. the ANSI color codes.
  525.  
  526. Eleven lines of the form (one for each report)
  527.  
  528. "Filename  Down columns(Y/N)  Columns   Number   Points" 
  529.  
  530. for calls, messages, uploads, downloads, doors, carrier drops,
  531. security violations, newest users, best users, BBS losers, all
  532. users.  (The value for "points" doesn't matter for newest, top,
  533. bottom, and all users.)
  534.  
  535. Three lines of the form (one for each triple list)
  536.  
  537. "Filename    #   cat. 1, cat. 2, cat. 3; 
  538.  
  539. where 0 = calls, 1 = messages, ..., 9 = worst users.
  540.  
  541. ---- END OF OPTION FILE ----
  542.  
  543. The Down columns Y/N must be in column 10.  The numbers must be
  544. delimited by at least one blank from anything else.
  545.  
  546. If the path names are blank the program looks for the activity
  547. log (ACTIVITY.LOG for Wildcat, or the sysop supplied name for the
  548. PowrBBS version) and user data file (USERFILE.DAT for Wildcat,
  549. USERS for PowrBBS) in the current directory and writes the data
  550. files to the directory specified in the output path.
  551.  
  552.  
  553. EDITING USER DATA:
  554.  
  555. The installation program will also let you edit user data. 
  556. Standard editing keys work here.  You can use this to add user
  557. data, change data, or print a list of users. 
  558.  
  559. You can use the "Add users" to set up the database if you want
  560. to.  Note that there is no error checking to make sure that the
  561. record number or name is not the same as one already in the data
  562. file. Recall that Top40 will automatically compile all data that
  563. is in the activity log.  
  564.  
  565. Note: the "Add users" option described above has been disabled
  566. since it is not of much use.  The program automatically adds all
  567. users it finds in the activity log.  Future versions will have
  568. the option of reading the Wildcat user data file to include all
  569. users - even if they aren't in the activity log.  Please let me
  570. know if you need the manual "add users" option back.
  571.  
  572. You can use the "Edit user" function to change data on a user. 
  573. You can change any of his statistic fields.  For instance, you
  574. may decide to not credit the user for one upload.  You also
  575. specify whether or not this user is to be included in the output
  576. lists.  If he is not included his statistics will still be
  577. tabulated - they just are ignored on the lists.
  578.  
  579. The "Edit user" give you a pick list to choose the desired user. 
  580. Once a user has been selected in the "Edit user" function you can
  581. use <PageUp> and <PageDown> to scroll through the user records.
  582.  
  583.  
  584. PURGE DELETED USERS FROM THE TOP40 DATA FILE:
  585.  
  586. Top40 keeps its own data file (Top40.DAT).  If you delete users
  587. from the Wildcat user data file they are not automatically
  588. deleted from Top40's data file.  If you run WCRepair after
  589. deleting users from the Wildcat user data file, you can then
  590. update Top40's data file by running the "Purge deleted users"
  591. option in the installation program (Top40I).
  592.  
  593.  
  594. EXECUTION:
  595.  
  596. Once the program is installed, the BBS can either call the
  597. program Top40 after the completion of each call or as an event. 
  598. If it is run as an event it must be run before any process that
  599. deletes or purges the activity log.  Top40 reads the new call
  600. records from the file activity log, updates its own data file
  601. (Top40.DAT), and generates ASCII files with the top user lists.
  602.  
  603. If the file Top40.DAT does not exist (it shouldn't initially)
  604. then Top40 will build it.  It will read the entire activity log
  605. and create and build Top40.DAT, including all of the information
  606. in the activity log.  If you ever want to zero out the statistics
  607. simply delete the file Top40.DAT.
  608.  
  609. WILDCAT should call the program Top40 after each call or as an
  610. event.  The data files it needs (other than the activity log and
  611. the user data file) are expected to be in the current directory,
  612. so it is best to make the directory with Top40 (and its data
  613. files) the current directory before running it.  The program
  614. requires 96K of available memory in order to work.  This program
  615. reads the activity log and builds the files it needs.
  616.  
  617. Note that Top40 currently gets all of its information from the
  618. activity log.  It initially builds its data file from the entire
  619. log, thereafter it gets the new caller records from the activity
  620. log and updates those user's records.  It is best to initialize
  621. the data file with the most complete set of activity logs you can
  622. get.  Your lists may not have many stats until you get enough
  623. calls.  Also, an old user who is not in the activity log when the
  624. data file is built will be considered a new user the next time he
  625. calls.
  626.  
  627. One registered user uses Top40 to award a prize for the best user
  628. each month, then start the statistics over at the beginning of
  629. the next month.  This is easily accomplished by deleting the
  630. following files at the end of the month: the activity log,
  631. Top40.DAT, and Top40.SIZ.  This will cause Top40 to start the
  632. data file over from scratch.  (It is important to purge Top40.SIZ
  633. only if Top40 is run as an event instead of after each call.  See
  634. "Purging the activity log and running Top40 as an event.)
  635.  
  636.  
  637. LIMITATIONS, ETC:
  638.  
  639. The program is currently limited to 1500 active users.  Note that
  640. the program will work with over 1500 users, but the statistics
  641. will be compiled for only the first 1500 active users found in
  642. the activity log.  Generally your oldest users are the most
  643. faithful and have called the most number of times, so that limit
  644. shouldn't be a major problem.  We are planning a future version
  645. that will allow for as many users as the BBS allows.
  646.  
  647. Each user can have up to 65,535 instances of each of the
  648. categories ("calls" through "security violations") recorded.  The
  649. points calculated for a user can be from -2 billion to +2
  650. billion, but if it exceeds 100 million or is less than -10
  651. million then the bulletin will not print properly (number field
  652. will overflow).  Therefore the weights should be reasonably small
  653. numbers.  The sum of the positive weights should be less than
  654. 1,526 (99,999,999 / 65,535 = 1,525.9).  Similarly, the sum of the
  655. negative weights should be greater than -153 (less than 153 in
  656. absolute value.)
  657.  
  658. You can set a number up to 65,535 for the number of users to
  659. appear on a given list.  If there are fewer users, only the
  660. actual number of users will appear.  For instance, if you have
  661. 400 users, if you set the number of users to appear on a list at
  662. 1,000, for example, only 400 users will appear on the list - you
  663. will not get 600 "zeros".  This is a way to list everyone's
  664. standings.
  665.  
  666. If a caller never enters the correct password the call is *not*
  667. counted (i.e. it doesn't count as a security violation or
  668. abnormal disconnect).  The reason is that the caller was probably
  669. not who he said he was.
  670.  
  671. For the three-column list format - the user's name will be
  672. abbreviated by the program if it is too long.  It will be given
  673. as a first initial and last name (not truncated) unless the last
  674. name is extremely long.  
  675.  
  676. Top40 takes on the order of 6 to 8 seconds to read, compile the
  677. data, update the data file, and write all of the ASCII bulletins
  678. on a 8 MHz AT with a 28ms hard disk, without disk caching
  679. software (no ANSI bulletins).  About 3/4s of this time is
  680. consumed by writing all of the ASCII file bulletins to disk, and
  681. there isn't much we can do to speed that up.  So don't have it to
  682. generate bulletins you aren't going to use if you want to save a
  683. little time.  Incidentally, even though the program reads the
  684. activity log - once the program has been installed and run once,
  685. the running time of Top40 does *not* increase as the activity log
  686. gets large.
  687.  
  688. Top40 currently limits the maximum number of "newest users"
  689. listed to 40.
  690.  
  691. PwrTop40 currently works on node 1 only!  A multi-node version
  692. will be forthcoming if there is demand for it.
  693.  
  694.  
  695. USE OF WCTop40 WITH S-PRO!:
  696.  
  697. If you are running S-PRO! with the 'kill activity log' option on,
  698. please note that Top40 will only list those calls it finds in the
  699. actual activity log.  If you use Top40 you will find that only
  700. those calls will be used and no previous history will be listed. 
  701. I am trying to get the information needed to allow Top40 to
  702. initialize with S-PRO!'s .HST file.
  703.  
  704.  
  705. PURGING THE ACTIVITY LOG AND RUNNING TOP40 AS AN EVENT:
  706.  
  707. There is one extra thing you (or a batch file) should do if you
  708. run Top40 as an event.  Each time the activity log is purged you
  709. should delete the file Top40.SIZ.  
  710.  
  711. The reason for deleting Top40.SIZ when the activity log is purged
  712. is as follows:  When the program Top40 runs it stores the current
  713. size of the activity log in the file Top40.SIZ.  This tells the
  714. program where to start reading in the activity log next time it
  715. is run.  If the file Top40.SIZ is missing or the number in the
  716. file is larger than the actual size of the activity log file the
  717. program will read and compile all of the activity log.  Otherwise
  718. it will start reading at that byte in the activity log.  Deleting
  719. Top40.SIZ when the activity log is purged will eliminate what
  720. would otherwise be an unlikely but potential problem if the
  721. activity log was deleted and then build up to an even larger size
  722. between two runs of Top40.  
  723.  
  724. If you are using version 1.3, 1.4x, or 1.5x, then the conversion
  725. program will generate the file Top40.SIZ based on the current
  726. activity log when you convert the data file.
  727.  
  728.  
  729. ERRORS:
  730.  
  731. If Top40 is unable to find the activity log or other needed file
  732. then it will write an error message to the screen (with a beep)
  733. and also write the error message to a file "Top40.ERR".
  734.  
  735.  
  736. HOW BUGS CREEP INTO PROGRAMS:
  737.  
  738. This section is meant to be an apology of and an explanation of
  739. how bugs creeped into this program, and a view of what goes on
  740. behind the scenes.  Sometimes a program feature that used to work
  741. doesn't work anymore.  This section gives a human view of the
  742. program development and debugging process.
  743.  
  744. One such bug caused Top40 (versions before 2.1) to not work with
  745. Wildcat version 2.15.  All of the record numbers were being
  746. listed as zero.  We did not have Wildcat version 2.15 yet, and
  747. registered user Don Bill sent me a sample of his activity log
  748. under Wildcat 2.15 along with a listing of his users (from the
  749. Top40 installation program).  (Thanks Don.)  The problem was that
  750. versions of Wildcat prior to version 2.15 listed "Record number:"
  751. as the second line of the calling record in the activity log. 
  752. Top40 scanned for those words and then read the next few
  753. characters to get the record number.  Top40 was using the record
  754. number to match up calling records with records in its database. 
  755. In Wildcat version 2.15 the wording was changed from "Record
  756. number:" to simply "Record:" so Top40 couldn't find the phrase
  757. for which it was searching.  A human can look at printouts of the
  758. two types of activity logs for several minutes without noticing
  759. the difference.  But a dumb computer program is different.  
  760.  
  761. Another bug that several users encountered is that the Top40 data
  762. base would be corrupted when Top40 was run after a user was
  763. deleted, and WCRepair was run.  The problem is that WCRepair
  764. removes deleted users from the list and moves up the other users
  765. to fill the space - meaning that the user's record number
  766. changes.  Top40 was assuming that the record number never
  767. changed, so when it found that the record number and name found
  768. in the activity log didn't match with the name of that record
  769. number in its data base it believed that it was a new name.  This
  770. meant that callers after WCRepair was run would be listed under
  771. their old and new record numbers, and previous data associated
  772. with the record number would be lost.
  773.  
  774. Version 2.1 was to correct this problem.  Several reasonable
  775. approaches were considered.  One was to use the record number
  776. read from the activity log as a starting place to look for the
  777. name.  For instance, if record number 100 - John Doe was read in
  778. from the activity log the program would first look in its
  779. database to see if record number 100 was "John Doe".  If it was
  780. then everything is OK.  Otherwise it would know that the record
  781. numbers had been changed, so it would start looking at 101, then
  782. 102, etc for John Doe.  But this is a messy, unnecessarily
  783. complicated process.  Sysop Soren Fried suggested using the name
  784. only.  The record numbers really were used only to match up the
  785. records, so they can be ignored.  
  786.  
  787. So version 2.1 used the user names instead of record numbers. 
  788. (It still attempted to read the record number, however.)  This
  789. version left the names already in the data file in the same
  790. order, and it would add new users at the end.  This was working,
  791. except for the fact that it was still reading and updating the
  792. record numbers, and under Wildcat version 2.15 it couldn't find
  793. the record numbers, so they all would get record number 0 (and be
  794. listed as "invalid record number" on the screen when the program
  795. runs).
  796.  
  797. One drawback, however, is that it takes a program much longer to
  798. compare strings (such as names) than to compare numbers.  I
  799. estimated that a board with 1000 users with 100 calls per day
  800. running Top40 as a daily event on a 10 MHz XT would see roughly a
  801. 10 second increase in update time.  I thought that this might be
  802. objectionable, so I considered faster methods.  One method is to
  803. keep the records sorted alphabetically and using binary search on
  804. the names, which will find any name very quickly.  
  805.  
  806. Although the method given above is a very reasonable approach, I
  807. decided on something different for this application.  I made a
  808. study of users of our board, and I found that less than 6% of the
  809. users accounted for more than 50% of the calls!  So I decided to
  810. sort the users according to the number of calls, with the most
  811. frequent caller first.  That way, most callers will be found in
  812. the database very quickly.  This approach has a couple of other
  813. advantages too.  When a new user calls he is simply added to the
  814. end of the list.  If the records were sorted alphabetically by
  815. name a new user would have to be inserted into the middle of the
  816. list, which would require moving a lot of records to make room. 
  817. The records are easily maintained in order of the number of calls
  818. by moving up a record if this call gives him more calls than the
  819. one above him on the list.  The other advantage of this method is
  820. that the program compiles the top user lists by reading though
  821. the database inserting users if they should appear on the list. 
  822. The quicker it finds the top 40 (or whatever) the less shuffling
  823. of users on the list there will be.  For instance, under this
  824. method the top callers will be immediately found, since they are
  825. all at the first of the list.  Since the most frequent callers
  826. are likely to be ones with a large number of messages, uploads,
  827. etc, these lists can be compiled quickly too.
  828.  
  829. I implemented this sorting method in version 2.11 - or so I
  830. thought!  Unfortunately, for the sorting routine I simply copied
  831. a sorting routine I already had into this program.  Like most
  832. sorting routines, this one was written to sort in ascending
  833. order, whereas I really wanted to sort in descending order of the
  834. number of calls.  I failed to make this change in the routine,
  835. and I didn't discover the error until after a couple of minor
  836. releases.
  837.  
  838. This method of sorting user records in descending order of the
  839. number of calls should work well for our application, but it
  840. introduced another bug, which was discovered by sysop Cam DeBuck. 
  841. The list of "newest users" was not right.  The reason is that
  842. older versions of Top40 found the newest users simply by looking
  843. at the end of the database, since new users are given the highest
  844. record number and added to the end of the list.  If the records
  845. in the database are not sorted by record number then this won't
  846. be true, and I failed to think of it.  (It is difficult to think
  847. of all of the implications that such a change can cause in a
  848. program.)  That means either going back to the old order of the
  849. database, or getting the newest users by some other method. 
  850. Top40 now reads the Wildcat user data file to get the list of
  851. "newest users".  This has the advantage of working even when
  852. Top40's data file has been deleted.
  853.  
  854.  
  855. REMEMBER:
  856.  
  857. If the file "Top40.DAT" is missing then the program will compile
  858. all of the calls in the activity log otherwise it will add only
  859. the new calls.  This is useful for setting up the program.
  860.  
  861. Top40 requires an intact activity log to create the full user's
  862. history.  Otherwise the bulletins will only reflect what a user
  863. has done since the earliest date in the activity log.
  864.  
  865. If you want to use this utility, then the author asked that you
  866. register your copy.  The registration cost $20 and entitles you
  867. to future upgrades and support through the following bulletin
  868. board:
  869.  
  870.                       Bad Lands (QuickBBS)
  871.                   300/1200/2400/9600 HST 8,N,1.
  872.                         Sysop: Andy Smith
  873.                          (912) 247-6977
  874.  
  875. The latest version of Top40 should always be available on this
  876. board.  
  877.  
  878. If you like this program you may like my other WILDCAT! BBS
  879. utilities - WCFields and WC-B-Day:
  880.  
  881. WCFields checks user data fields for possible duplicate users. 
  882. It looks for duplicate phone numbers, duplicate birthdays, same
  883. or *similar* passwords, and same or *similar* names.
  884.  
  885. WC-B-Day generates bulletins listing users with birthdays this
  886. week or month.  This should be popular with the users.
  887.  
  888.  
  889. TOP40 VERSIONS:
  890.  
  891.   Alpha- 1-5-90.  Alpha test version.
  892.  
  893.  
  894.   Beta - 1-6-90.  Beta test on Land of Confusion BBS.
  895.  
  896.  
  897.   1.0  - 1-7-90.  Test version.
  898.  
  899.  
  900.   1.1  - 1-8-90.  Test version.
  901.  
  902.  
  903.   1.2  - 1-9-90.  Test version.
  904.  
  905.  
  906.   1.3  - 1-10-90.  Initial released version.
  907.  
  908.  
  909.   1.4  - Added "newest users" list.  
  910.  
  911.          Miscellaneous changes.
  912.  
  913.          Options file format change.
  914.  
  915.  
  916.   1.5  - Added "all users" list.  
  917.  
  918.          Miscellaneous changes.
  919.  
  920.          Options file format change.
  921.  
  922.  
  923.   1.51 - Redefined "top users", misc. changes (unreleased).
  924.  
  925.  
  926.   1.52 - Fixed a bug crediting new users with an extra call.  
  927.  
  928.          Change report format to allow for > 999 users.
  929.  
  930.  
  931.   1.53 - 1-20-90
  932.  
  933.          No longer writes disk files if no change (excluded user
  934.          or login failure, etc).
  935.  
  936.          Make sure excluded users do not appear on lists.
  937.          Previously if a user gathers statistics and then is
  938.          excluded his old stats would continue to appear on
  939.          lists.
  940.   
  941.  
  942.   2.0  - 1-25-90 (limited release)
  943.  
  944.          Can run as an event or after each call.
  945.   
  946.          More efficient reading of the activity log.
  947.  
  948.          Full editing of user data.
  949.  
  950.          Ability to include or exclude each user.
  951.  
  952.          Option of two or three column format.
  953.  
  954.          Option of going down columns instead of across.
  955.  
  956.          Options file format change.
  957.  
  958.          Data file format change.
  959.          (A reserved byte now used to indicate inclusion).
  960.  
  961.  
  962.   2.01 - 1-27-90
  963.  
  964.          Checks to make sure printer is on before print list.
  965.  
  966.          New users default to "include" (caused blank lines).
  967.  
  968.  
  969.   2.02 - 1-30-90
  970.  
  971.          Adding new users allows entry of the name and record #.
  972.  
  973.  
  974.   2.03 - 1-31-90
  975.  
  976.          Make all four option screens accessible from the menu.
  977.  
  978.  
  979.   2.04 - 2-2-90
  980.  
  981.          Raise limit from 1000 to 1500 active users.
  982.  
  983.  
  984.   2.1  - 4-8-90 (limited release)
  985.  
  986.          Support for Wildcat 2.15.
  987.  
  988.          Added ANSI screen option.
  989.  
  990.          Added countdown to #1 option.
  991.  
  992.          Fixed the bug caused when WCRepair deletes a user.
  993.  
  994.          Options file format change.
  995.  
  996.  
  997.   2.11 - 4-9-90 (limited release)
  998.  
  999.          Fixed bug where long path & file names are truncated.
  1000.  
  1001.          Ignore record numbers in activity log.
  1002.  
  1003.          Faster updating of Top40's data file.
  1004.  
  1005.          Faster compilation of information for lists.
  1006.  
  1007.          Faster writing of triple lists to disk.
  1008.  
  1009.          Pick users alphabetically.                   
  1010.  
  1011.          Eliminate "add users" in installation program. 
  1012.          Is it needed?                       
  1013.  
  1014.  
  1015.   2.12 - 4-10-90 (limited release)
  1016.  
  1017.          Added error message file.
  1018.  
  1019.  
  1020.   2.13 - 4-10-90 (limited release)
  1021.  
  1022.          Fixed sorting error for faster updating of data.
  1023.     
  1024.  
  1025.   2.14 - 4-16-90
  1026.  
  1027.          Fixed bug in "newest user" list that was introduced in
  1028.          version 2.1.
  1029.  
  1030.          Fixed bug where 2-column across was listing downward.
  1031.  
  1032.  
  1033.   2.2 - 5-17-90
  1034.       
  1035.          Fixed bug with storing a changed background color in the
  1036.          ANSI screens.
  1037.  
  1038.          The "Delete users" function in the installation program
  1039.          was replaced by "Purge deleted users" which will delete
  1040.          all users that have been deleted from the Wildcat user
  1041.          database (after WCRepair has been run).
  1042.  
  1043.          Add path to USERFILE.DAT.
  1044.  
  1045.  
  1046.   2.3 ALPHA - 6-2-90 
  1047.  
  1048.          Added extension option for ASCII files.
  1049.  
  1050.          Option file format change.
  1051.  
  1052.          WCT40C23 - conversion from version 2.1x & 2.2 to 2.3.
  1053.  
  1054.          Alpha release for testing on PowrBBS.
  1055.  
  1056.  
  1057.   2.3 BETA - 6-3-90
  1058.  
  1059.         Release of version 2.3 BETA.
  1060.  
  1061.  
  1062.   2.3 GAMMA - 6-4-90
  1063.         
  1064.         Changes for PowrBBS bulletin files:
  1065.           no extension
  1066.           append "C" for ANSI color screens
  1067.  
  1068.  
  1069.   2.3  - 6-5-90 (Limited release)
  1070.    
  1071.        Allow PowrBBS sysops to enter the activity log file name.
  1072.  
  1073.  
  1074.   2.31 - 6-12-90 (limited release)
  1075.  
  1076.        Fixed bug with activity path and file name.
  1077.  
  1078.  
  1079.   2.32 - 6-12-90 (limited release)
  1080.  
  1081.        Fixed bug with ANSI file names in PowrBBS version.
  1082.  
  1083.        More descriptive error message and file.
  1084.  
  1085.  
  1086.   2.33 - 6-12-90 
  1087.  
  1088.        Fixed bug in PowrBBS version with renaming activity log.
  1089.  
  1090.   2.34 - date unknown
  1091.     
  1092.        Smaller EXE files.
  1093.  
  1094.  
  1095.   2.4 - 11-22-90 
  1096.  
  1097.        Faster reading and writing of disk files.
  1098.  
  1099.  
  1100.   2.5 - 2-6-91
  1101.  
  1102.        Fixed bug in Wildcat installation program
  1103.        Added option of user data file name.
  1104.  
  1105.  
  1106.   2.6 alpha - 4-14-91
  1107.  
  1108.       Alpha test of QuickBBS version.
  1109.  
  1110.  
  1111.   2.6 - 4-16-91
  1112.  
  1113.       QuickBBS version released.
  1114.        
  1115.  
  1116. PLANNED ENHANCEMENTS IN FUTURE VERSIONS:
  1117.  
  1118.   Unlimited number of users.
  1119.  
  1120.   Faster updating of records.
  1121.  
  1122.   Pick users alphabetically by last name.
  1123.  
  1124.   More list categories:
  1125.     Most recent callers
  1126.     Total time connected
  1127.     Total kilobytes uploaded
  1128.     Total kilobytes downloaded
  1129.     
  1130.  
  1131. ACKNOWLEDGMENTS:
  1132.  
  1133. Thanks to the users who sent in suggestions and the users who
  1134. have registered the program.  In particular, thanks to Bob Lias,
  1135. Cam DeBuck, and Don (I forgot the last name).
  1136.  
  1137. Thanks to Guy Tyson for suggesting the program, being an alpha
  1138. and beta tester, for putting up with half a dozen different test
  1139. versions (often with file formats incompatible with previous
  1140. versions), for finding a few bugs, for publicizing the program,
  1141. and for letting the "Land of Confusion" be the home board for
  1142. Top40.  (JM)
  1143.  
  1144. Thanks to the Andy Smith, sysop of the Bad Lands BBS for being
  1145. the test board and home board for the PowrBBS and QuickBBS
  1146. versions of Top40, and the support board for the Wildcat version.
  1147.  
  1148. WILDCAT! BBS is by Mustang Software.
  1149.  
  1150. PowrBBS is by Russell Frey.
  1151.  
  1152. QuickBBS is by S. Gabrilowitz and R. Creighton.
  1153.  
  1154. This program was written in Turbo Pascal 5.5 from Borland
  1155. International.  The Turbo Professional 5.0 package by Turbo Power
  1156. software provided routines for screen editing in the setup
  1157. program, as well as a few other useful functions.  The EXE files
  1158. were compressed using PKLITE Professional from PK Software.
  1159.  
  1160.  
  1161. Program by: Jud McCranie
  1162.  
  1163. Documentation by: Jud McCranie and Guy Tyson
  1164.